//////////////////////////////////////////////////////////////////////////////////
//
// ActionScript 3.0 Common Library (MIT License)
// Copyright (c) 2009 AS3CommonCode | Tony Birleffi | http://www.mosaiceye.com
// 
// Permission is hereby granted, free of charge, to any person
// obtaining a copy of this software and associated documentation
// files (the "Software"), to deal in the Software without
// restriction, including without limitation the rights to use,
// copy, modify, merge, publish, distribute, sublicense, and/or sell
// copies of the Software, and to permit persons to whom the
// Software is furnished to do so, subject to the following
// conditions:
// 
// The above copyright notice and this permission notice shall be
// included in all copies or substantial portions of the Software.
// 
// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
// EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
// OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
// NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
// HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
// WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
// FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
// OTHER DEALINGS IN THE SOFTWARE.
//
//////////////////////////////////////////////////////////////////////////////////

package org.as3commoncode.utils 
{
	import flash.display.MovieClip;	
	import org.as3commoncode.utils.MathUtil;

	/**
	 * This is a usuful class for creating movie clips.
	 * 
	 * @author Tony Birleffi
	 */
	public class MovieClipUtil 
	{
		/**
		 * Use this method to create a movie clip.
		 * 
		 * @example
		 * <listing>
         * import org.as3commoncode.utils.MovieClipUtil;
         * var mc:MovieClip = MovieClipUtil.createMovieClip(0, 0, 'mc_1', { alpha:50 });
         * </listing>
         *
		 * @param xPos		x position.
		 * @param yPos		y position.
		 * @param name		string name of the mc.
		 * @param init		default is null, however you can pass any additional parameters, { alpha:50 }.
		 * @return MovieClip.
		 */
		public static function createMovieClip(xPos:Number = 0, yPos:Number = 0, name:String = null, init:Object = null):MovieClip
		{
			// Define the new movie clip.
			var mc:MovieClip = new MovieClip();
			
			// Set parameters.
			mc.x = xPos;
			mc.y = yPos;
			mc.name = (name == null) ? "mc" + MathUtil.random(0, 99999, 1) + "_mc" : name;
			
			// Pass any additional properties if need be here.
			if (init != null) for(var it:String in init) mc[ it ] = init[ it ];
			
			// Return.
			return mc;
		}
		
		/**
		 * Use this method to return an object of all the current labels
		 * contained in the current target movie clip passed.
		 * 
		 * @example
		 * <listing>
         * import org.as3commoncode.utils.MovieClipUtil;
         * var labels:Object = MovieClipUtil.getLabels(mc);
         * // returns { start:50, middle:75, end:150 }.
         * </listing>
         *
		 * @param target	current movie clip.
		 * @return Object.
		 */
		public static function getLabels(target:MovieClip):Object 
		{
			// Grab the current labels.
			var lbls:Array = target.currentLabels;
			
			// Define the labels object.
			var labels:Object = {};
			
			// Populate.
			for (var i:uint=0; i< lbls.length; i++) labels[ lbls[ i ].name ] = lbls[ i ].frame;
			
			// Return it.
			return labels;
		}
		
		/**
		 * Use this method to return a frame number based off 
		 * of either a number or string value.
		 * 
		 * @example
		 * <listing>
         * import org.as3commoncode.utils.MovieClipUtil;
         * var frameNum:uint = MovieClipUtil.getFrameNumber(mc, 'start');
         * </listing>
         *
		 * @param target	movie clip.
		 * @param frame		number or string label of the target movie clip.
		 * @return uint.
		 */
		public static function getFrameNumber(target:MovieClip, frame:*):uint 
		{
			// Grab the frame number.
			var frameNum:uint = uint(frame);
			if (frameNum) { return frameNum; };
			
			// Define the label.
			var label:String = String(frame);
			if (label == null) { return 0; }
			
			var labels:Object = MovieClipUtil.getLabels(target);
			frameNum = labels[ label ];
			return frameNum;
		}
	}
}
